Skip to main content

Getting Started

This guide will help you set up and run the FF-API-External service locally for development and testing purposes.

Table of Contents​

Prerequisites​

Before setting up FF-API-External, ensure you have the following prerequisites installed:

Required Software​

  • Python 3.11.9 (as specified in runtime.txt)
  • MySQL (5.7 or newer)
  • MongoDB (4.0 or newer)
  • Git (for cloning the repository)

Required API Keys​

You'll need API keys for the various third-party services:

  • OpenAI (ChatGPT)
  • Anthropic (Claude)
  • SERP API
  • Google Maps
  • Paystack
  • And others as needed for your specific use case

Installation​

Clone the Repository​

git clone https://github.com/yourusername/ff-api-external.git
cd ff-api-external

Create a Virtual Environment​

# Create a virtual environment using the correct Python version
python3.11 -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

Install Dependencies​

pip install -r requirements.txt

Configuration​

Environment Variables​

Create a .env file in the root directory with your configuration variables. Use the provided .env file as a template:

cp .env.example .env  # If .env.example exists
# Or create a new .env file manually

Edit the .env file with your specific configuration values:

# Database configurations
MYSQL_HOST=localhost
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password
MYSQL_DB=main
MYSQL_CURSORCLASS=DictCursor
MYSQL_PORT=3306

# MongoDB configurations
MONGODB_MAIN_PROD=mongodb://localhost:27017/gateway

# API keys for various services
CHAT_GPT_API_KEY=your-openai-api-key
CLAUDE_API_KEY=your-claude-api-key
# ... other API keys as needed

Database Setup​

MySQL Database​

  1. Create the MySQL database:
CREATE DATABASE main;
  1. Create a MySQL user with appropriate permissions:
CREATE USER 'your_mysql_user'@'localhost' IDENTIFIED BY 'your_mysql_password';
GRANT ALL PRIVILEGES ON main.* TO 'your_mysql_user'@'localhost';
FLUSH PRIVILEGES;
  1. Import the database schema (if provided):
mysql -u your_mysql_user -p main < schema.sql

MongoDB Database​

  1. Start the MongoDB service if it's not already running:
# On Linux
sudo systemctl start mongod

# On macOS with Homebrew
brew services start mongodb-community
  1. Create the necessary MongoDB database and collections:
// Connect to MongoDB
mongo

// Create the database
use gateway

// Create collections as needed
db.createCollection("gsmarena_brands")
db.createCollection("gsmarena_devices")
// ... other collections as needed

Certificate Files​

The repository includes certificate files for MongoDB:

  • ca-certificate.crt
  • mongodb-1-cert.crt

Ensure these files are in the correct location and have the proper permissions.

Running the Service​

Development Server​

For local development, you can use the built-in Flask development server:

python server.py

This will start the server on port 5060 with debug mode enabled, as specified in server.py.

Using Gunicorn (Production-like)​

For a more production-like environment, you can use Gunicorn:

gunicorn --config gunicorn_config.py wsgi:app

This will start the server on port 8080 as configured in gunicorn_config.py.

Using Docker (Optional)​

If you prefer to use Docker for development:

  1. Build the Docker image:
docker build -t ff-api-external .
  1. Run the container:
docker run -p 8080:8080 --env-file .env ff-api-external

API Testing​

Using Curl​

You can test the API endpoints using curl:

# Test a simple endpoint
curl -X GET "http://localhost:5060/api/v1/gsmarena/brands"

# Test an endpoint with parameters
curl -X POST "http://localhost:5060/api/v1/claude/prompt" \
     -d "prompt=Tell me about AI" \
     -d "max_tokens=1000" \
     -d "temperature=0.7"

Using Postman​

Postman provides a more user-friendly interface for API testing:

  1. Import the API collection (if provided) or create a new collection
  2. Configure environment variables for base URL and authentication
  3. Create requests for each endpoint you want to test
  4. Send requests and examine responses

Using Python Requests​

You can also test the API using Python's requests library:

import requests

# Test a simple endpoint
response = requests.get("http://localhost:5060/api/v1/gsmarena/brands")
print(response.json())

# Test an endpoint with parameters
data = {
    "prompt": "Tell me about AI",
    "max_tokens": 1000,
    "temperature": 0.7
}
response = requests.post("http://localhost:5060/api/v1/claude/prompt", data=data)
print(response.json())

Development Workflow​

Adding a New Endpoint​

To add a new endpoint:

  1. Identify the appropriate blueprint in the view/api/ directory
  2. Add a new route handler function:
@blueprint_name.route('/api/v1/your/endpoint', methods=['GET'])
@cross_origin()
def api_v1_your_endpoint():
    try:
        # Implementation...
        return resp.returnResponse(200, result)
    except Exception as e:
        return resp.returnResponse(400, f"Error: {str(e)}")
  1. Implement the required functionality in the appropriate service model

Adding a New Service Integration​

To add a new third-party service integration:

  1. Create a new service model in the models/ directory
  2. Create a new route blueprint in the view/api/ directory
  3. Register the blueprint in server.py

Code Style and Best Practices​

  • Follow PEP 8 for Python code style
  • Use docstrings to document functions and classes
  • Add appropriate error handling
  • Use the JsonResponse utility for consistent response formatting
  • Implement input validation using the Validation utility
  • Use environment variables for configuration

Troubleshooting Installation​

Common Issues​

ModuleNotFoundError​

ModuleNotFoundError: No module named 'module_name'

Solution: Ensure you have activated the virtual environment and installed all dependencies:

source venv/bin/activate
pip install -r requirements.txt

Database Connection Errors​

OperationalError: (2003, "Can't connect to MySQL server on 'localhost' (10061)")

Solution: Ensure MySQL server is running and the connection details in .env are correct.

API Key Errors​

APIError: Authentication error: Invalid API key

Solution: Check that you have set the correct API keys in the .env file.

Port Already in Use​

OSError: [Errno 98] Address already in use

Solution: Change the port in server.py or stop the process using the current port:

# Find the process using the port
lsof -i :5060  # Linux/macOS
netstat -ano | findstr :5060  # Windows

# Kill the process
kill -9 <PID>  # Linux/macOS
taskkill /F /PID <PID>  # Windows

Additional Support​

If you encounter issues not covered here, check the Troubleshooting guide for more detailed information.